home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / CIncludes / LocationManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  10.4 KB  |  365 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        LocationManager.h
  3.  
  4.      Contains:    LocationManager (manages groups of settings)
  5.  
  6.      Version:    Technology:    Mac OS 8
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __LOCATIONMANAGER__
  18. #define __LOCATIONMANAGER__
  19.  
  20. #ifndef __APPLEEVENTS__
  21. #include <AppleEvents.h>
  22. #endif
  23. #ifndef __COMPONENTS__
  24. #include <Components.h>
  25. #endif
  26. #ifndef __DIALOGS__
  27. #include <Dialogs.h>
  28. #endif
  29. #ifndef __PROCESSES__
  30. #include <Processes.h>
  31. #endif
  32. #ifndef __STANDARDFILE__
  33. #include <StandardFile.h>
  34. #endif
  35.  
  36.  
  37.  
  38. #if PRAGMA_ONCE
  39. #pragma once
  40. #endif
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. #if PRAGMA_IMPORT
  47. #pragma import on
  48. #endif
  49.  
  50. #if PRAGMA_STRUCT_ALIGN
  51.     #pragma options align=mac68k
  52. #elif PRAGMA_STRUCT_PACKPUSH
  53.     #pragma pack(push, 2)
  54. #elif PRAGMA_STRUCT_PACK
  55.     #pragma pack(2)
  56. #endif
  57.  
  58. /* Location Manager API Support -------------------------------------------------------------------- */
  59. /* A Location Token uniquely identifies a Location on a machine... */
  60.  
  61. typedef struct OpaqueALMToken*             ALMToken;
  62. #define kALMNoLocationToken    ((ALMToken)(-1))  // ALMToken of "off" Location...
  63.  
  64. enum {
  65.     kALMLocationNameMaxLen        = 31,                            /* name (actually imposed by file system)... */
  66.     kALMNoLocationIndex            = -1                            /* index for the "off" Location (kALMNoLocationToken)... */
  67. };
  68.  
  69. typedef Str31                             ALMLocationName;
  70. /* Returned from ALMConfirmName... */
  71. typedef SInt16                             ALMConfirmChoice;
  72.  
  73. enum {
  74.     kALMConfirmRename            = 1,
  75.     kALMConfirmReplace            = 2
  76. };
  77.  
  78. /* ALMConfirmName dialog item numbers for use in callbacks (ALM 2.0)... */
  79.  
  80.  
  81. enum {
  82.     kALMDuplicateRenameButton    = 1,                            /* if Window refcon is kALMDuplicateDialogRefCon... */
  83.     kALMDuplicateReplaceButton    = 2,
  84.     kALMDuplicateCancelButton    = 3,
  85.     kALMDuplicatePromptText        = 5
  86. };
  87.  
  88.  
  89. enum {
  90.     kALMRenameRenameButton        = 1,                            /* if Window refcon is kALMRenameDialogRefCon... */
  91.     kALMRenameCancelButton        = 2,
  92.     kALMRenameEditText            = 3,
  93.     kALMRenamePromptText        = 4
  94. };
  95.  
  96. /* Refcons of two windows in ALMConfirmName (ALM 2.0)... */
  97.  
  98.  
  99. enum {
  100.     kALMDuplicateDialogRefCon    = FOUR_CHAR_CODE('dupl'),
  101.     kALMRenameDialogRefCon        = FOUR_CHAR_CODE('rnam')
  102. };
  103.  
  104. /* Callback routine for Location awareness (mimics AppleEvents) in non-application code... */
  105.  
  106. typedef CALLBACK_API( void , ALMNotificationProcPtr )(AppleEvent *theEvent);
  107. typedef STACK_UPP_TYPE(ALMNotificationProcPtr)                     ALMNotificationUPP;
  108. enum { uppALMNotificationProcInfo = 0x000000C0 };                 /* pascal no_return_value Func(4_bytes) */
  109. #define NewALMNotificationProc(userRoutine)                     (ALMNotificationUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppALMNotificationProcInfo, GetCurrentArchitecture())
  110. #define CallALMNotificationProc(userRoutine, theEvent)             CALL_ONE_PARAMETER_UPP((userRoutine), uppALMNotificationProcInfo, (theEvent))
  111. /* Notification AppleEvents sent to apps/registered code...  */
  112.  
  113. enum {
  114.     kAELocationChangedNoticeKey    = FOUR_CHAR_CODE('walk'),        /* Current Location changed... */
  115.     kAELocationRescanNoticeKey    = FOUR_CHAR_CODE('trip')        /* Location created/renamed/deleted... */
  116. };
  117.  
  118. /* ALMSwitchToLocation masks... */
  119.  
  120. typedef SInt32                             ALMSwitchActionFlags;
  121.  
  122. enum {
  123.     kALMDefaultSwitchFlags        = 0x00000000,                    /* No special action to take... */
  124.     kALMDontShowStatusWindow    = 0x00000001,                    /* Suppress "switching" window... */
  125.     kALMSignalViaAE                = 0x00000002                    /* Switch by sending Finder AppleEvent... */
  126. };
  127.  
  128. /* Parameters for Get/Put/Merge Location calls... */
  129.  
  130. typedef const OSType *                    ConstALMModuleTypeListPtr;
  131.  
  132. enum {
  133.     kALMAddAllOnSimple            = 0,                            /* Add all single-instance, non-action modules... */
  134.     kALMAddAllOff                = -1                            /* Add all modules but turn them off... */
  135. };
  136.  
  137. /* Item numbers for use in Get/Put/Merge Location filters... */
  138.  
  139.  
  140. enum {
  141.     kALMLocationSelectButton    = 1,
  142.     kALMLocationCancelButton    = 2,
  143.     kALMLocationBalloonHelp        = 3,
  144.     kALMLocationLocationList    = 7,
  145.     kALMLocationLocationNameEdit = 10,
  146.     kALMLocationPromptText        = 11
  147. };
  148.  
  149.  
  150. enum {
  151.     kALMLocationSaveButton        = kALMLocationSelectButton
  152. };
  153.  
  154. /* Location Manager Module API Support ------------------------------------------------------------- */
  155.  
  156. /* ALMGetScriptInfo stuff... */
  157.  
  158.  
  159. enum {
  160.     kALMScriptInfoVersion        = 2                                /* Customarily put in resource for localization... */
  161. };
  162.  
  163.  
  164. struct ALMScriptManagerInfo {
  165.     SInt16                             version;                    /* Set to kALMScriptInfoVersion... */
  166.     SInt16                             scriptCode;
  167.     SInt16                             regionCode;
  168.     SInt16                             langCode;
  169.     SInt16                             fontNum;
  170.     SInt16                             fontSize;
  171. };
  172. typedef struct ALMScriptManagerInfo        ALMScriptManagerInfo;
  173. typedef ALMScriptManagerInfo *            ALMScriptManagerInfoPtr;
  174. /*
  175.    Alternate form of ScriptInfo is easier to localize in resources; it is used extensively in
  176.    samples and internally, so....
  177. */
  178.  
  179. struct ALMAltScriptManagerInfo {
  180.     SInt16                             version;
  181.     SInt16                             scriptCode;
  182.     SInt16                             regionCode;
  183.     SInt16                             langCode;
  184.     SInt16                             fontSize;
  185.     Str63                             fontName;
  186. };
  187. typedef struct ALMAltScriptManagerInfo    ALMAltScriptManagerInfo;
  188. typedef ALMAltScriptManagerInfo *        ALMAltScriptManagerInfoPtr;
  189. typedef ALMAltScriptManagerInfoPtr *    ALMAltScriptManagerInfoHandle;
  190.  
  191. enum {
  192.     kALMAltScriptManagerInfoRsrcType = FOUR_CHAR_CODE('trip'),
  193.     kALMAltScriptManagerInfoRsrcID = 0
  194. };
  195.  
  196. /* Reboot information used on ALMSetCurrent (input/output parameter)... */
  197.  
  198.  
  199. typedef UInt32                             ALMRebootFlags;
  200.  
  201. enum {
  202.     kALMNoChange                = 0,
  203.     kALMAvailableNow            = 1,
  204.     kALMFinderRestart            = 2,
  205.     kALMProcesses                = 3,
  206.     kALMExtensions                = 4,
  207.     kALMWarmBoot                = 5,
  208.     kALMColdBoot                = 6,
  209.     kALMShutdown                = 7
  210. };
  211.  
  212. /*
  213.    File types and signatures...
  214.    Note: auto-routing of modules will not be supported for 'thng' files...
  215. */
  216.  
  217.  
  218. enum {
  219.     kALMFileCreator                = FOUR_CHAR_CODE('fall'),        /* Creator of Location Manager files... */
  220.     kALMComponentModuleFileType    = FOUR_CHAR_CODE('thng'),        /* Type of a Component Manager Module file [v1.0]... */
  221.     kALMComponentStateModuleFileType = FOUR_CHAR_CODE('almn'),    /* Type of a CM 'state' Module file... */
  222.     kALMComponentActionModuleFileType = FOUR_CHAR_CODE('almb'),    /* Type of a CM 'action' Module file... */
  223.     kALMCFMStateModuleFileType    = FOUR_CHAR_CODE('almm'),        /* Type of a CFM 'state' Module file... */
  224.     kALMCFMActionModuleFileType    = FOUR_CHAR_CODE('alma')        /* Type of a CFM 'action' Module file... */
  225. };
  226.  
  227. /* Component Manager 'thng' info... */
  228.  
  229.  
  230. enum {
  231.     kALMComponentRsrcType        = FOUR_CHAR_CODE('thng'),
  232.     kALMComponentType            = FOUR_CHAR_CODE('walk')
  233. };
  234.  
  235. /* CFM Modules require a bit of information (replacing some of the 'thng' resource)... */
  236.  
  237.  
  238. enum {
  239.     kALMModuleInfoRsrcType        = FOUR_CHAR_CODE('walk'),
  240.     kALMModuleInfoOriginalVersion = 0
  241. };
  242.  
  243. /* These masks apply to the "Flags" field in the 'thng' or 'walk' resource... */
  244.  
  245.  
  246. enum {
  247.     kALMMultiplePerLocation        = 0x00000001,                    /* Module can be added more than once to a Location... */
  248.     kALMDescriptionGetsStale    = 0x00000002                    /* Descriptions may change though the setting didn't...  */
  249. };
  250.  
  251. /* Misc stuff for older implementations ------------------------------------------------------------ */
  252.  
  253. #if OLDROUTINENAMES
  254. /* Old error codes for compatibility - new names are in Errors interface... */
  255.  
  256. enum {
  257.     ALMInternalErr                = -30049,                        /* use kALMInternalErr */
  258.     ALMLocationNotFound            = -30048,                        /* use kALMLocationNotFoundErr */
  259.     ALMNoSuchModuleErr            = -30047,                        /* use kALMNoSuchModuleErr */
  260.     ALMModuleCommunicationErr    = -30046,                        /* use kALMModuleCommunicationErr */
  261.     ALMDuplicateModuleErr        = -30045,                        /* use kALMDuplicateModuleErr */
  262.     ALMInstallationErr            = -30044,                        /* use kALMInstallationErr */
  263.     ALMDeferSwitchErr            = -30043                        /* use kALMDeferSwitchErr */
  264. };
  265.  
  266. /* Old ALMConfirmName constants... */
  267.  
  268.  
  269. enum {
  270.     ALMConfirmRenameConfig        = kALMConfirmRename,
  271.     ALMConfirmReplaceConfig        = kALMConfirmReplace
  272. };
  273.  
  274. /* Old AppleEvents... */
  275.  
  276.  
  277. enum {
  278.     kAELocationNotice            = kAELocationChangedNoticeKey
  279. };
  280.  
  281. typedef ALMScriptManagerInfo             ALMScriptMgrInfo;
  282. typedef UInt32                             ALMComponentFlagsEnum;
  283. #endif  /* OLDROUTINENAMES */
  284.  
  285. /* Location Manager API ---------------------------------------------------------------------------- */
  286.  
  287. /* The following 7 routines are present if gestaltALMAttr has bit gestaltALMPresent set... */
  288.  
  289. EXTERN_API( OSErr )
  290. ALMGetCurrentLocation            (SInt16 *                index,
  291.                                  ALMToken *                token,
  292.                                  ALMLocationName         name)                                THREEWORDINLINE(0x303C, 0x0600, 0xAAA4);
  293.  
  294. EXTERN_API( OSErr )
  295. ALMGetIndLocation                (SInt16                 index,
  296.                                  ALMToken *                token,
  297.                                  ALMLocationName         name)                                THREEWORDINLINE(0x303C, 0x0501, 0xAAA4);
  298.  
  299. EXTERN_API( OSErr )
  300. ALMCountLocations                (SInt16 *                locationCount)                        THREEWORDINLINE(0x303C, 0x0202, 0xAAA4);
  301.  
  302. EXTERN_API( OSErr )
  303. ALMSwitchToLocation                (ALMToken                 newLocation,
  304.                                  ALMSwitchActionFlags     switchFlags)                        THREEWORDINLINE(0x303C, 0x0403, 0xAAA4);
  305.  
  306. EXTERN_API( OSErr )
  307. ALMRegisterNotifyProc            (ALMNotificationUPP     notificationProc,
  308.                                  const ProcessSerialNumber * whichPSN)                        THREEWORDINLINE(0x303C, 0x0404, 0xAAA4);
  309.  
  310. EXTERN_API( OSErr )
  311. ALMRemoveNotifyProc                (ALMNotificationUPP     notificationProc,
  312.                                  const ProcessSerialNumber * whichPSN)                        THREEWORDINLINE(0x303C, 0x0405, 0xAAA4);
  313.  
  314. EXTERN_API( OSErr )
  315. ALMConfirmName                    (ConstStr255Param         message,
  316.                                  Str255                 theName,
  317.                                  ALMConfirmChoice *        choice,
  318.                                  ModalFilterUPP         filter)                                THREEWORDINLINE(0x303C, 0x0806, 0xAAA4);
  319.  
  320. /* The following 3 routines are present if gestaltALMAttr has bit gestaltALMHasSFLocation set... */
  321.  
  322. EXTERN_API( OSErr )
  323. ALMPutLocation                    (ConstStr255Param         prompt,
  324.                                  ALMLocationName         name,
  325.                                  SInt16                 numTypes,
  326.                                  ConstALMModuleTypeListPtr  typeList,
  327.                                  ModalFilterYDUPP         filter,
  328.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0B07, 0xAAA4);
  329.  
  330. EXTERN_API( OSErr )
  331. ALMGetLocation                    (ConstStr255Param         prompt,
  332.                                  ALMLocationName         name,
  333.                                  ModalFilterYDUPP         filter,
  334.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0808, 0xAAA4);
  335.  
  336. EXTERN_API( OSErr )
  337. ALMMergeLocation                (ConstStr255Param         prompt,
  338.                                  ALMLocationName         name,
  339.                                  SInt16                 numTypes,
  340.                                  ConstALMModuleTypeListPtr  typeList,
  341.                                  ModalFilterYDUPP         filter,
  342.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0B09, 0xAAA4);
  343.  
  344.  
  345. #if PRAGMA_STRUCT_ALIGN
  346.     #pragma options align=reset
  347. #elif PRAGMA_STRUCT_PACKPUSH
  348.     #pragma pack(pop)
  349. #elif PRAGMA_STRUCT_PACK
  350.     #pragma pack()
  351. #endif
  352.  
  353. #ifdef PRAGMA_IMPORT_OFF
  354. #pragma import off
  355. #elif PRAGMA_IMPORT
  356. #pragma import reset
  357. #endif
  358.  
  359. #ifdef __cplusplus
  360. }
  361. #endif
  362.  
  363. #endif /* __LOCATIONMANAGER__ */
  364.  
  365.